Atom AI Labs - AI-Powered Multi-Tenant Platform

Package Management System

Overview

The Package Management System enables safe installation of Python packages for agent skill execution while maintaining security isolation. It provides:

**Whitelist-based access control** - Packages must be approved for agent maturity levels
**Vulnerability scanning** - All packages scanned with pip-audit before installation
**Fast installation** - Uses uv (10-100x faster than pip)
**Per-skill isolation** - Each skill gets its own virtualenv
**Comprehensive audit logging** - All installations logged for security investigations

**Note:** This implementation currently supports Python packages only. npm package support for OpenClaw canvas components is planned as a future enhancement. See the Future Enhancements section for details.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        API Layer                                 │
│  POST /api/packages/install                                     │
│  GET /api/packages/whitelist                                    │
│  POST /api/packages/whitelist (admin)                           │
│  GET /api/packages/installations                                │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                    Service Layer                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  PackageWhitelistService                                 │  │
│  │  - can_install_package()                                 │  │
│  │  - get_packages_for_maturity()                            │  │
│  │  - add_package_to_whitelist()                             │  │
│  └──────────────────────┬───────────────────────────────────┘  │
│                         │                                       │
│  ┌──────────────────────▼───────────────────────────────────┐  │
│  │  PackageScannerService                                   │  │
│  │  - scan_package() [pip-audit integration]                │  │
│  │  - cache_scan_result() [Redis, 24h TTL]                  │  │
│  └──────────────────────┬───────────────────────────────────┘  │
│                         │                                       │
│  ┌──────────────────────▼───────────────────────────────────┐  │
│  │  PackageInstallationService                              │  │
│  │  - install_package_for_skill() [uv installer]            │  │
│  │  - rollback_package()                                    │  │
│  │  - get_installed_packages()                              │  │
│  └──────────────────────┬───────────────────────────────────┘  │
└──────────────────────────┼──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                      Data Layer                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌────────────────┐ │
│  │ package_whitelist│  │package_installations│ │ Redis Cache   │ │
│  └─────────────────┘  └─────────────────┘  └────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Security Flow

1. Installation Request
       │
       ▼
2. Whitelist Validation
   ├── Package approved for maturity level?
   │   └── NO → Block installation (403 Forbidden)
   └── Version constraint satisfied?
       └── NO → Block installation (400 Bad Request)
       │
       ▼
3. Vulnerability Scan
   ├── Run pip-audit on package
   │   └── CVEs found? → Block installation (403 Forbidden)
   └── Cache scan result (24h TTL)
       │
       ▼
4. Install with uv
   ├── Create per-skill virtualenv
   ├── Run: uv pip install package
   └── Capture installed version
       │
       ▼
5. Audit Logging
   └── Record to package_installations table
       │
       ▼
6. Return Installation Result

Agent Maturity Levels

Level	Access	Example Packages	Max Memory
student	Pre-approved packages only	pandas, numpy	512MB
intern	Student + web packages	requests, beautifulsoup4	512MB
supervised	Intern + ML packages	scikit-learn	1GB
autonomous	All packages (with approval)	torch, transformers (approval req.)	2GB+

**Maturity Hierarchy:** Lower levels inherit packages from higher levels. For example, a supervised agent can install all packages approved for student and intern levels.

API Endpoints

POST /api/packages/install

Install Python package for skill execution.

**Request:**

{
  "package_name": "pandas",
  "version_constraint": ">=2.0.0",
  "skill_id": "skill-abc123",
  "agent_maturity": "student"
}

**Response (200 OK):**

{
  "success": true,
  "package_name": "pandas",
  "version": "2.0.3",
  "install_path": "/tmp/skill_venvs/tenant_xyz_skill_abc123",
  "vulnerabilities_found": 0,
  "installed_at": "2026-02-19T12:00:00Z"
}

**Error Responses:**

403 Forbidden - Package not in whitelist or vulnerabilities found
400 Bad Request - Invalid version constraint
500 Internal Server Error - Installation failed

**Example:**

curl -X POST "https://api.atomagentos.com/api/packages/install" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "package_name": "pandas",
    "version_constraint": ">=2.0.0,<3.0.0",
    "skill_id": "skill-data-processor",
    "agent_maturity": "student"
  }'

GET /api/packages/whitelist

Get approved packages for agent maturity level.

**Query Parameters:**

maturity_level (optional, default="student") - Filter by maturity level
category (optional) - Filter by category

**Response (200 OK):**

[
  {
    "package_name": "pandas",
    "version_constraint": ">=2.0.0,<3.0.0",
    "maturity_level": "student",
    "max_memory_mb": 512,
    "network_access": false,
    "requires_approval": false,
    "description": "Data analysis library",
    "category": "data-science"
  }
]

**Example:**

# Get all student-level packages
curl "https://api.atomagentos.com/api/packages/whitelist?maturity_level=student" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get data-science packages for supervised agents
curl "https://api.atomagentos.com/api/packages/whitelist?maturity_level=supervised&category=data-science" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/packages/whitelist (Admin Only)

Add package to whitelist.

**Request:**

{
  "package_name": "new-package",
  "version_constraint": ">=1.0.0",
  "maturity_level": "student",
  "max_memory_mb": 512,
  "network_access": false,
  "requires_approval": false,
  "description": "Package description",
  "category": "category-name"
}

**Response (201 Created):** Returns created whitelist entry

**Error (403 Forbidden):** User is not admin

**Example:**

curl -X POST "https://api.atomagentos.com/api/packages/whitelist" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "package_name": "openpyxl",
    "version_constraint": ">=3.1.0,<4.0.0",
    "maturity_level": "supervised",
    "max_memory_mb": 256,
    "network_access": false,
    "requires_approval": false,
    "description": "Excel file reader/writer",
    "category": "data-io"
  }'

DELETE /api/packages/whitelist/{package_name} (Admin Only)

Remove package from whitelist.

**Response (204 No Content):** Package removed successfully

**Example:**

curl -X DELETE "https://api.atomagentos.com/api/packages/whitelist/old-package" \
  -H "Authorization: Bearer ADMIN_TOKEN"

GET /api/packages/installations

Get package installation audit log for tenant.

**Query Parameters:**

limit (default: 100, max: 500) - Maximum entries to return
package_name (optional) - Filter by package name
skill_id (optional) - Filter by skill ID

**Response (200 OK):**

[
  {
    "id": "inst-abc123",
    "tenant_id": "tenant-xyz",
    "agent_id": "agent-123",
    "skill_id": "skill-abc",
    "package_name": "pandas",
    "version": "2.0.3",
    "maturity_level_at_install": "student",
    "vulnerabilities_found": 0,
    "installation_status": "completed",
    "installed_at": "2026-02-19T12:00:00Z",
    "installed_by": "user-123",
    "uninstalled_at": null
  }
]

**Example:**

# Get recent installations
curl "https://api.atomagentos.com/api/packages/installations?limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get all pandas installations
curl "https://api.atomagentos.com/api/packages/installations?package_name=pandas" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get installations for specific skill
curl "https://api.atomagentos.com/api/packages/installations?skill_id=skill-data-processor" \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE /api/packages/{package_name}

Uninstall package for skill (rollback).

**Request:**

{
  "skill_id": "skill-abc123"
}

**Response (204 No Content):** Package uninstalled successfully

**Example:**

curl -X DELETE "https://api.atomagentos.com/api/packages/pandas" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"skill_id": "skill-data-processor"}'

GET /api/packages/installed

Get list of currently installed packages for tenant/skill.

**Query Parameters:**

skill_id (optional) - Filter by skill ID

**Response (200 OK):**

[
  {
    "package_name": "pandas",
    "version": "2.0.3",
    "skill_id": "skill-data-processor",
    "installed_at": "2026-02-19T12:00:00Z",
    "vulnerabilities_found": 0
  }
]

**Example:**

# Get all installed packages for tenant
curl "https://api.atomagentos.com/api/packages/installed" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get packages for specific skill
curl "https://api.atomagentos.com/api/packages/installed?skill_id=skill-data-processor" \
  -H "Authorization: Bearer YOUR_TOKEN"

Admin Guide

Viewing Installation History

Monitor what packages are being installed:

curl -X GET "https://api.atomagentos.com/api/packages/installations?limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Adding Packages to Whitelist

As an admin, add new packages to the whitelist:

curl -X POST "https://api.atomagentos.com/api/packages/whitelist" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "package_name": "new-package",
    "version_constraint": ">=1.0.0,<2.0.0",
    "maturity_level": "supervised",
    "max_memory_mb": 1024,
    "network_access": true,
    "requires_approval": false,
    "description": "Package for data processing",
    "category": "data-science"
  }'

Investigating Security Incidents

Query installation logs for suspicious activity:

# Get all installations by a specific tenant
curl "https://api.atomagentos.com/api/packages/installations?limit=500" \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq '.[] | select(.tenant_id == "suspicious-tenant")'

# Find installations with vulnerabilities
curl "https://api.atomagentos.com/api/packages/installations" \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq '.[] | select(.vulnerabilities_found > 0)'

Managing Default Whitelist

The default whitelist is stored in config/package_whitelist_default.yaml. To update:

Edit the YAML file with new packages
Run the seeding function:

db = SessionLocal()

service = PackageWhitelistService(db)

service.seed_default_whitelist("config/package_whitelist_default.yaml")

```

Or use the admin API to add packages individually.

Security Best Practices

1. Always Validate Against Whitelist

Never allow packages that aren't explicitly approved. The whitelist is your primary defense against typosquatting attacks and malicious packages.

2. Scan for Vulnerabilities

Every package installation must go through pip-audit scanning. Vulnerabilities in dependencies are also detected.

3. Use Per-Skill Isolation

Each skill gets its own virtualenv to prevent dependency conflicts and limit the blast radius of compromised packages.

4. Cache Wisely

Vulnerability scan results are cached for 24 hours. This balances performance with security (vulnerability databases update daily).

5. Log Everything

All installation attempts (success and failure) are logged. This is critical for security investigations and compliance.

6. Maturity-Based Access

Lower maturity levels have restricted access. Only autonomous agents can request packages that require admin approval.

7. Version Constraints

Always use version constraints in the whitelist (e.g., >=2.0.0,<3.0.0) to prevent unexpected breaking changes.

8. Regular Audits

Review the installation audit log regularly for:

Unusual package installation patterns
Failed installation attempts (possible attack probing)
Packages with vulnerabilities that were somehow installed

Troubleshooting

Installation Fails with "Package not in whitelist"

**Cause:** The package is not approved for the agent's maturity level.

**Solution:** Either:

Request a package with lower maturity requirements
Ask admin to add package to whitelist
Increase agent maturity level (requires graduation exam)

**Example:**

{
  "error": "Package 'requests' not approved for student agents",
  "allowed": false
}

Installation Fails with "Vulnerabilities found"

**Cause:** The package has known CVEs.

**Solution:**

Check if a newer version is available that fixes the CVEs
Request admin override (if risk is acceptable)
Find an alternative package without vulnerabilities

**Example:**

{
  "error": "Package 'old-package' has 3 known vulnerabilities",
  "vulnerabilities_found": 3,
  "vulnerability_details": [
    {
      "cve": "CVE-2023-1234",
      "severity": "HIGH",
      "affected_versions": "<1.2.3"
    }
  ]
}

Installation Timeout

**Cause:** Package is too large or network issues.

**Solution:**

Check network connectivity
Increase timeout in service configuration
Consider pre-building Docker images with large packages

Virtualenv Not Found

**Cause:** Skill's virtualenv was cleaned up or never created.

**Solution:**

Re-install the package
Check cleanup job configuration
Verify SKILL_VENV_BASE_PATH is accessible

Package Name Normalization Issues

**Cause:** Package names with underscores vs hyphens.

**Note:** Package names are automatically normalized to lowercase with hyphens (e.g., "my_package" → "my-package"). Both variants will work in API requests.

Configuration

Environment Variables

Variable	Default	Description
`SKILL_VENV_BASE_PATH`	`/tmp/skill_venvs`	Base directory for skill virtualenvs
`REDIS_URL`	-	Redis URL for scan result caching
`EMBEDDING_DIM`	`1536`	Embedding dimension (from platform config)

Whitelist Configuration

The default whitelist is configured in config/package_whitelist_default.yaml:

tiers:
  student:
    - package: pandas
      version: ">=2.0.0,<3.0.0"
      max_memory_mb: 512
      network_access: false
      category: data-science

    - package: numpy
      version: ">=1.24.0,<2.0.0"
      max_memory_mb: 512
      network_access: false
      category: data-science

  intern:
    - package: requests
      version: ">=2.28.0,<3.0.0"
      max_memory_mb: 256
      network_access: true
      category: web

    - package: beautifulsoup4
      version: ">=4.12.0,<5.0.0"
      max_memory_mb: 256
      network_access: true
      category: web

  supervised:
    - package: scikit-learn
      version: ">=1.3.0,<2.0.0"
      max_memory_mb: 1024
      network_access: false
      category: ml

  autonomous:
    - package: torch
      version: ">=2.0.0"
      max_memory_mb: 2048
      network_access: false
      requires_approval: true
      category: ml

    - package: transformers
      version: ">=4.35.0"
      max_memory_mb: 2048
      network_access: false
      requires_approval: true
      category: ml

Performance Considerations

uv vs pip

Using uv instead of pip provides 10-100x faster installation:

**pip**: ~30 seconds for pandas + numpy
**uv**: ~3 seconds for pandas + numpy

Scan Result Caching

Caching pip-audit results for 24 hours reduces repeated scans of the same package by ~90%.

Pre-Built Images

For frequently used packages (pandas, numpy, requests), consider building Docker images with these packages pre-installed. This eliminates installation latency for those packages.

Future Enhancements: npm Support

Current Implementation

The package management system currently supports **Python packages only**. This is designed for agent skills that execute Python code in isolated environments.

Planned npm Support

**OpenClaw canvas components** can use npm packages since they run in a browser/Node.js environment. Future enhancements will include:

**Dual Package Management**

Python packages for agent skill execution (current implementation)
npm packages for canvas component dependencies (planned)

**Integration Approach**

**Security Parity**

Whitelist validation for npm packages
Vulnerability scanning with npm audit
Per-component isolation (similar to per-skill virtualenvs)

**Implementation Timeline**

Phase 59: Design npm package architecture
Phase 60: Implement npm package management
Phase 61: Unified package management API

Current Workaround

For canvas components that need npm packages:

Include dependencies in component's package.json
Install during component build/deployment phase
Use existing npm security audit tools

Example: Future API

# Future: Install npm package for canvas component
POST /api/packages/npm/install
{
  "package_name": "lodash",
  "version_constraint": "^4.17.21",
  "component_id": "comp-dashboard"
}

# Future: Get npm whitelist
GET /api/packages/npm/whitelist?category=utilities

Integration with Canvas Skills

See CANVAS_SKILL_INTEGRATION.md for details on using Python packages in canvas skills.

Example: Canvas Skill with Python Dependencies

# SKILL.md for canvas skill
name: data-visualization
description: Visualizes CSV data with charts
dependencies:
  python:
    - package: pandas
      version: ">=2.0.0"
    - package: matplotlib
      version: ">=3.7.0"

The package management system will automatically:

Validate dependencies against whitelist
Scan for vulnerabilities
Install packages in isolated virtualenv
Log installation for audit

Package Management System

Overview

Architecture

Security Flow

Agent Maturity Levels

API Endpoints

POST /api/packages/install

GET /api/packages/whitelist

POST /api/packages/whitelist (Admin Only)

DELETE /api/packages/whitelist/{package_name} (Admin Only)

GET /api/packages/installations

DELETE /api/packages/{package_name}

GET /api/packages/installed

Admin Guide

Viewing Installation History

Adding Packages to Whitelist

Investigating Security Incidents

Managing Default Whitelist

Security Best Practices

1. Always Validate Against Whitelist

2. Scan for Vulnerabilities

3. Use Per-Skill Isolation

4. Cache Wisely

5. Log Everything

6. Maturity-Based Access

7. Version Constraints

8. Regular Audits

Troubleshooting

Installation Fails with "Package not in whitelist"

Installation Fails with "Vulnerabilities found"

Installation Timeout

Virtualenv Not Found

Package Name Normalization Issues

Configuration

Environment Variables

Whitelist Configuration

Performance Considerations

uv vs pip

Scan Result Caching

Pre-Built Images

Future Enhancements: npm Support

Current Implementation

Planned npm Support

Current Workaround

Example: Future API

Integration with Canvas Skills

Example: Canvas Skill with Python Dependencies

References